//===============================================================================
// Microsoft patterns & practices
// SharePoint Guidance version 2.0
//===============================================================================
// Copyright (c) Microsoft Corporation.  All rights reserved.
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY
// OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
// LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
// FITNESS FOR A PARTICULAR PURPOSE.
//===============================================================================
// The example companies, organizations, products, domain names,
// e-mail addresses, logos, people, places, and events depicted
// herein are fictitious.  No association with any real company,
// organization, product, domain name, email address, logo, person,
// places, or events is intended or should be inferred.
//===============================================================================
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Permissions;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;
using Microsoft.SharePoint.Security;

namespace Microsoft.Practices.SPG.Common.Configuration
{
    /// <summary>
    /// Interface for classes that can read from and write to a config store, in a hierarchical and typesafe manner. 
    /// 
    /// The config store is implemented in IPropertyBags. They can either point tot he property bags of:
    ///  - SPFarm
    ///  - SPWebApplication
    ///  - SPSite
    ///  - SPWeb
    /// 
    /// Lower level propertybags inherit the values of their parents but can override them as well.. 
    /// 
    /// </summary>
    [SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
    [SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
    public interface IConfigManager
    {

        /// <summary>
        /// Remove a configvalue from a specified propertybag and all it's children. 
        /// </summary>
        /// <param name="key">The configsetting to remove</param>
        /// <param name="propertyBag">The propertyBag to remove it from</param>
        [SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
        [SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
        void Remove(string key, IPropertyBag propertyBag);

        /// <summary>
        /// Read a config value based on the key, from the default propertybag: SPContext.Current.Web
        /// </summary>
        /// <typeparam name="TValue">The type of the value to read. </typeparam>
        /// <param name="key">The key associated with the config value</param>
        /// <returns>The value</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1004:GenericMethodsShouldProvideTypeParameter"), SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
        [SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
        TValue GetByKey<TValue>(string key);

        /// <summary>
        /// Read a config value based on the key, from the specified propertybag.
        /// </summary>
        /// <typeparam name="TValue">The type of the value to read.</typeparam>
        /// <param name="key">The key associated with the config value</param>
        /// <param name="propertyBag">The property bag to read values from.</param>
        /// <returns>The value</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1004:GenericMethodsShouldProvideTypeParameter"), SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
        [SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
        TValue GetByKey<TValue>(string key, IPropertyBag propertyBag);

        /// <summary>
        /// Sets a config value for a specific key in the specified propertybag
        /// </summary>
        /// <param name="key">The key for this config setting</param>
        /// <param name="value">The value to give this config setting</param>
        /// <param name="propertyBag">the propertybag to store the setting in</param>
        [SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
        [SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
        void SetByKey(string key, object value, IPropertyBag propertyBag);

        /// <summary>
        /// Sets a config value for a specific key in the specified propertybag
        /// </summary>
        /// <param name="key">The key for this config setting</param>
        /// <param name="value">The value to give this config setting</param>
        /// <param name="propertyBag">the propertybag to store the setting in</param>
        [SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
        [SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
        void SetByKey(string key, object value, SPWeb propertyBag);

        /// <summary>
        /// Sets a config value for a specific key in the specified propertybag
        /// </summary>
        /// <param name="key">The key for this config setting</param>
        /// <param name="value">The value to give this config setting</param>
        /// <param name="propertyBag">the propertybag to store the setting in</param>
        [SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
        [SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
        void SetByKey(string key, object value, SPSite propertyBag);

        /// <summary>
        /// Sets a config value for a specific key in the specified propertybag
        /// </summary>
        /// <param name="key">The key for this config setting</param>
        /// <param name="value">The value to give this config setting</param>
        /// <param name="propertyBag">the propertybag to store the setting in</param>
        [SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
        [SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
        void SetByKey(string key, object value, SPWebApplication propertyBag);

        /// <summary>
        /// Sets a config value for a specific key in the specified propertybag
        /// </summary>
        /// <param name="key">The key for this config setting</param>
        /// <param name="value">The value to give this config setting</param>
        /// <param name="propertyBag">the propertybag to store the setting in</param>
        [SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
        [SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
        void SetByKey(string key, object value, SPFarm propertyBag);

        /// <summary>
        /// The default property bag that's used by the configmanager. 
        /// </summary>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate", Justification = "Must be a method, because implementation throws exceptions")
        , SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
        [SharePointPermission(SecurityAction.LinkDemand, ObjectModel = true)] 
        IPropertyBag GetDefaultPropertyBag();

        /// <summary>
        /// Determines if a configvalue with the specified key can be found in config. 
        /// Will recursively look up to parent propertybags to find the key. 
        /// </summary>
        /// <param name="key">the specified key</param>
        /// <returns>
        /// 	<c>true</c> if the specified key contains key; otherwise, <c>false</c>.
        /// </returns>
        bool ContainsKey(string key);

        /// <summary>
        /// Determines if a configvalue with the specified key can be found in the specified propertybag.
        /// Will recursively look up to parent propertybags to find the key.
        /// </summary>
        /// <param name="key">The key.</param>
        /// <param name="propertyBag">The property bag.</param>
        /// <returns>
        /// 	<c>true</c> if the specified key contains key; otherwise, <c>false</c>.
        /// </returns>
        bool ContainsKey(string key, IPropertyBag propertyBag);
    }
}
